home *** CD-ROM | disk | FTP | other *** search
/ The World of Computer Software / The World of Computer Software.iso / tbav503.zip / STACKMAN.DOC < prev    next >
Text File  |  1992-12-29  |  13KB  |  269 lines
  1.  
  2. Documentation for StackMan Stack Manager.
  3.  
  4.  
  5. What can StackMan do for you?
  6.  
  7.     Have you ever experienced your machine hanging unexpectedly? Have
  8.     you ever experienced programs dumping beeping garbage on the screen?
  9.     Ever found your overnight working machine hanging when you return
  10.     to work even though the same programs work well during the day? Ever
  11.     seen the message "Stack overflow"? Found some resident or background
  12.     software to hang the machine as soon as you want to activate them?
  13.     Does your system run unreliably when you put the statement
  14.     "Stacks=0,0" in your Config.Sys file? Do some programs crash when
  15.     using them in combination with some TSR's?
  16.  
  17.     If you can answer all these questions with "No" the Stack Manager
  18.     will not be useful for you.
  19.  
  20.     If some of these events frequently happen to you, these problems are
  21.     likely caused by stack overflows. Mostly these problems can be
  22.     solved by using the Config.Sys statement "Stacks 9,256". Sometimes
  23.     not. Anyway, the "Stacks" statement consumes precious memory and it
  24.     is hard to guess the correct values. The "Stacks" statement is not
  25.     explained very well in most documentations. Only a few users seem
  26.     to understand its purpose.
  27.  
  28.  
  29. What is a stack and how does it fail?
  30.  
  31.     A stack is a memory buffer used by software and the processor itself
  32.     to store temporary data. All programs establish a stack when they
  33.     are executed, but background or resident software have to use the
  34.     stack of the foreground program. As soon as you press a key the
  35.     processor is interrupted by the keyboard processor to fetch the
  36.     pressed key. Every timer tick the processor is interrupted to
  37.     increase the system timer. All these background processes consume
  38.     some stack space. Sometimes there is a timer tick, a keyboard
  39.     interrupt and another interrupt at the same time. It will not happen
  40.     often, but when it happens, all these processes need some stack
  41.     space at the same time. If it is not available the system will
  42.     simply hang... And as you might expect, these random events are hard
  43.     to reproduce...
  44.  
  45.     Although it is recommended to supply plenty of stack space in a
  46.     program, many programmers keep the stack very small to save memory,
  47.     especially if the program is intended to remain resident in memory.
  48.     Of course resident programs can set up their own temporary stack as
  49.     soon as they are activated, but before they are able to do that they
  50.     need to use some of the foreground stack space, and the resident
  51.     stack is often also very small for obvious reasons. If you have a lot 
  52.     of resident software and/or background software the stack might be too
  53.     small in some cases.
  54.  
  55.     To avoid these problems DOS is able to maintain a stack pool and it
  56.     switches to a dedicated stack if a hardware interrupt occurs. The
  57.     "Stacks" statement in the Config.Sys can be used to control this
  58.     stack pool.
  59.  
  60.     However, the DOS stack switching has some drawbacks and this is one
  61.     of the reasons why StackMan has been developed.
  62.  
  63.  
  64. Features of StackMan
  65.  
  66.     StackMan offers the same functionality as the DOS "Stacks" command,
  67.     but in addition to this:
  68.  
  69.     -   If you use DOS 5.00, StackMan can be loaded high and/or into the
  70.         HMA. DOS instead always maintains the stack pool in conventional 
  71.         memory. When using StackMan you free up about 1.5Kb of memory.
  72.  
  73.     -   The parameters of StackMan are more flexible. You can define just
  74.         one stack frame if it is sufficient. The minimum of DOS is 8.
  75.  
  76.     -   StackMan can be loaded AFTER your TSR's become resident. This
  77.         causes the TSR's to use the stackspace provided by StackMan. The
  78.         DOS stacks pool however is only available for the DOS and BIOS
  79.         code. TSR's still use the foreground program's stack, and if this
  80.         causes problems the DOS stacks command will not solve this.
  81.  
  82.     -   The DOS stacks command offers the user a type of roulette: the
  83.         only way to find the correct values is by trial and error. StackMan
  84.         can print a report and it is easy to find out the stack requirements
  85.         of your system configuration. It is easy to fine-tune the StackMan
  86.         parameters to suit your system configuration perfectly.
  87.  
  88.     -   Sometimes DOS stacks seem to disappear. Although this can be
  89.         considered as a bug from one of the TSR's or foreground programs
  90.         it is hard to deal with the resulting DOS message "Stack
  91.         overflow. System halted". This never happens immediately but a while
  92.         after the offending program corrupted a stack. StackMan however
  93.         recognizes this situation and it will automatically recover the lost
  94.         stack without interrupting the program.
  95.  
  96.     Although StackMan can be used to replace the DOS stacks command it has
  97.     additional features:
  98.  
  99.     -   In some cases the total stack requirements of all resident int 21h
  100.         handlers may exceed the available stack space, especially if using
  101.         a program that maintains a tiny stack (like some popular swap
  102.         utilities). Although these programs may perform well at the machine
  103.         of the developer, many other users may experience problems.
  104.         StackMan can be used to force a normal stack space for DOS at all
  105.         times.
  106.  
  107.     -   To be safe TSR's should maintain their own stack, but that means
  108.         that the TSR program would occupy some extra memory to hold the
  109.         stack. If only 1% of the users need that stack and the other
  110.         systems can run without it, it is not very convenient to install 
  111.         a dedicated stack in all cases. Being the author of TbScanX and
  112.         Thunderbyte this dilemma applies to me. In 99.9% of the
  113.         configurations my products perform very well, but a few systems
  114.         hang when these products are used in combination with some other
  115.         software. Should I convert my products to consume extra memory
  116.         only to solve the problems of the unhappy few? There should be a
  117.         better way. And now there is a better way... StackMan is able to
  118.         handle stack requests, and TSR programs may ask StackMan to
  119.         setup a temporary stack. Many TSR programs can share a few
  120.         of the stacks provided by StackMan. The stack is available
  121.         when the TSR activates, and gone as soon as the TSR resumes
  122.         system control. It just saves memory...
  123.  
  124.  
  125. Usage
  126.  
  127.     Before using StackMan it is recommended to put the statement
  128.     "Stacks=0,0" into the Config.Sys file. Using any other (or the
  129.     default values) just causes DOS to waste memory.
  130.  
  131.     The syntax of StackMan is:
  132.         StackMan [[=] <num of stacks),<stack size>] [<options...>]
  133.  
  134.     The best place to invoke StackMan is at the end of your Autoexec.Bat
  135.     file. This way resident software will use the stacks provided by
  136.     StackMan automatically.
  137.  
  138.     You can highload StackMan if you want to.
  139.  
  140.     As a first test it is recommended to use large values like:
  141.         StackMan = 18,384
  142.  
  143.     Now use the system as you do normally and test if some of the
  144.     problems are solved. Invoke all TSR's you have and try also to
  145.     activate multiple TSR's at the same time. Use your modem, mouse,
  146.     etc. It is not necessary to execute large programs since they have
  147.     their own stack and they will not affect the results of StackMan.
  148.  
  149.     Now run StackMan again. You should see something like this:
  150.  
  151.     ┌─────────────────────────────────────────────────────────────┐
  152.     │                                                             │
  153.     │   StackMan already installed, with 18 stacks of 384 bytes.  │
  154.     │   Maximum stacks/space ever used:  6 stacks of 112 bytes.   │
  155.     │                                                             │
  156.     └─────────────────────────────────────────────────────────────┘
  157.  
  158.     You can now reduce the parameter values of StackMan.
  159.     It is highly recommended to maintain some extra overhead. "Special
  160.     events" are very hard to reproduce. Reliable values for this example
  161.     are: "StackMan = 8,192".
  162.  
  163.     If the first value of the StackMan report is below or equal to 3 and
  164.     the second does not exceed 48 you can use your system without
  165.     StackMan. In other cases unlikely events are able to crash the
  166.     machine and you should use StackMan to avoid random problems.
  167.  
  168.     It is recommended to check the output of StackMan once in a while
  169.     to fine-tune the system and anticipate on increasing stack requirements
  170.     of your configuration.
  171.  
  172.  
  173.     If still some of the problems occur you can test if the -dos parameter
  174.     solves it. Specify this on the command line after a reboot:
  175.         StackMan = 18,384 -dos -noirq
  176.  
  177.     The report of StackMan should now be treated differently: the first
  178.     value will always show the maximum stacks amount available, only
  179.     the stackspace used is reliable. If this value exceeds 48 you should
  180.     consider use of the -dos option of StackMan.
  181.  
  182.     If the first test shows that you have to use StackMan anyway you should
  183.     remove the -noirq option. If only DOS needs StackMan you can keep this
  184.     parameter. If you use the -dos option you should allocate two extra
  185.     stack frames in addition to the values achieved by the first test.
  186.  
  187.  
  188. Options available
  189.  
  190.     The following options are available:
  191.  
  192.     -help
  193.         This option shows a little help screen.
  194.  
  195.     -dos
  196.         This option causes StackMan to force a fresh stack before
  197.         entering DOS. This may solve some problems, especially if they
  198.         occur at program startup or termination or in combination with
  199.         swapping shell programs.
  200.  
  201.     -noirq
  202.         If you specify this option StackMan will not switch the stack
  203.         after an interrupt occurs. The only functionality left in this
  204.         case is the -dos option and the stack sharing of StackMan-
  205.         supporting TSR programs.
  206.  
  207.     -hma
  208.         This option can only be specified if you are using DOS 5+ when
  209.         DOS is loaded into the HMA (with the dos=high statement). You
  210.         can not use this option in combination with the -dos option.
  211.         The -hma option causes StackMan to keep the stacks in the HMA
  212.         space left by DOS. Although this saves memory you should test
  213.         very thoroughly if your system allows the use of the HMA by
  214.         StackMan.
  215.  
  216.  
  217. StackMan API
  218.  
  219.     If you are software developer and wish to make use of StackMan this
  220.     chapter will be useful for you.
  221.  
  222.     Your TSR program should check the segment pointed to by int B4h.
  223.     If you find the string "STACKXXX' at offset 0Ah the stack manager
  224.     is installed. The next byte (at offset 12h) contains the version
  225.     number of StackMan in BCD form. The word at offset 14h contains the
  226.     number of stacks available, and the word at offset 16h specifies the
  227.     size of each stack.
  228.  
  229.     To request a new stack execute "Int B4h". All registers and flags are
  230.     preserved. The interrupt returns with a new private stack.
  231.  
  232.     To restore the original stack execute "Int B5h". Of course all
  233.     registers and flags are preserved. Register SP should have the value
  234.     provided by "Int B4h" before executing "Int B5h". This will normally
  235.     automatically be the case.
  236.  
  237.     StackMan will issue an install-broadcast when it goes resident. The
  238.     broadcast is issued by invoking int 2Fh with the value C9FFh in
  239.     register AX, the BCD version number in register BL, the number of
  240.     stacks in register CX and the stacksize in register DX.
  241.  
  242.     Hint: If StackMan is not installed make Int B4h and Int B5h point to
  243.     an "iret" instruction. If you do this you don't have to make decisions
  244.     in the resident part of your program. Just execute Int B4h/B5h whether
  245.     StackMan is installed or not.
  246.  
  247.  
  248. License agreement
  249.  
  250.     StackMan is FreeWare. As long as you meet these requirements/restrictions
  251.     you are entitled to use and distribute it:
  252.  
  253.     -   StackMan.Exe and StackMan.Doc are copyrighted by Thunderbyte B.V.
  254.  
  255.     -   It is not allowed to spread modified parts of the StackMan package.
  256.  
  257.     -   Thunderbyte B.V. nor Frans Veldman accepts any responsibilities for
  258.         the use or results of the use of StackMan. Being the user of
  259.         StackMan you are fully responsible for the results of StackMan.
  260.  
  261.     -   You are allowed to distribute StackMan with your products as long
  262.         as credit is given to Thunderbyte B.V. AND Frans Veldman.
  263.  
  264.  
  265.     StackMan is written by Frans Veldman, chief executive of Thunderbyte
  266.     B.V. in The Netherlands.
  267.  
  268.  
  269.